1. 先看整體架構

整體長得像是這樣：

                            CAPEv2 Host ( Ubuntu 24.04 LTS )
                                          │
                          ┌───────────────┼────────────────┐
                          │               │                │
                         CAPE           KVM/QEMU         Rooter
                          │               │                │
                          │        ┌──────┴──────┐         │
                          │        │ Windows VM  │         │
                          │        │             │         │
                          │        │ CAPE Agent  │         │
                          │        └──────┬──────┘         │
                          │               │                │
                          └───────────────┼────────────────┘
                                          │
                                          │
                                          ▼
                                API / Hook / PCAP
                                Memory / YARA / IOC
                                          │
                                          ▼
                                    Web UI / API

CAPE 的核心能力包括 API hooking、檔案異動、PCAP、行為簽章、螢幕截圖、記憶體 dump、unpacking、YARA 分類與 configuration/payload extraction。([GitHub][1])

---

整體安裝我區分四個結構

1. 初始設定

   1. ubuntu 安裝注意

2. kvm-qemu

3. CAPEv2.git

4. Windows VM

   1. 環境安裝
   2. CAPE Agent 設定

2. 最低需求：先說官方與實務的差異

官方「最低需求」

目前官方文件沒有給一個明確的最低 CPU / RAM / SSD 數字。官方比較強調：

• Ubuntu 24.04 LTS Host
• KVM/QEMU
• Windows 10 或 Windows 11 23H2 Guest
• CPU 必須能跑硬體虛擬化
• VM 必須支援 Snapshot
• Guest 要能與 Host 的 Result Server 通訊
• 足夠磁碟空間；cuckoo.conf 預設 freespace 是 50 GB。([GitHub][1])

因此網路上「8 GB RAM、4 Core、200 GB」之類的數字，多半是社群實作建議，不是 CAPEv2 官方硬性最低需求。

「實驗室最低可行」

單台 Windows VM、低併發：

項目	最低可行	建議
CPU	4 核	8 核以上
RAM	16 GB	32 GB
Host SSD	150 GB	300 GB+
Guest VM RAM	4–6 GB	8 GB
Guest VM CPU	2 vCPU	4 vCPU
Guest 數量	1	2–4
網卡	2 NIC 較好	管理/分析流量分離
CPU 虛擬化	必須	VT-x/AMD-V + KVM

這是部署建議，不是官方 minimum。

如果預計同時跑多個 Windows VM，真正的瓶頸通常會是 RAM、CPU 和儲存 I/O，而不是 CAPE 本身。

---

3. 最重要的 Host OS：Ubuntu 24.04 LTS

官方目前最強烈建議：

Ubuntu 24.04 LTS

而目前 kvm-qemu.sh 也明確標示它是針對 Ubuntu 24.04。([GitHub][1])
不要一開始就在你的 Ubuntu Docker Desktop 環境裡硬塞 CAPEv2。
原因是 CAPEv2 的核心是：

KVM
libvirt
QEMU
iptables / routing
VM snapshots
network isolation

這些都是 Host 虛擬化層的東西。

應該採取的架構：

實體伺服器
└── Ubuntu 24.04
      ├── CAPEv2
      ├── KVM/QEMU
      └── Windows VM

---

4. CPU 虛擬化確認

Intel：

grep -E 'vmx' /proc/cpuinfo

AMD：

grep -E 'svm' /proc/cpuinfo

應該有輸出。

BIOS/UEFI 要啟用：

Intel VT-x
或
AMD-V

---

5. 安裝前一定要做的事情

建立一台：

Ubuntu 24.04 LTS

然後先確認環境狀態：

hostnamectl
uname -a
lscpu
free -h
df -h
ip addr
ip route

再確認 KVM：

ls /dev/kvm

理想狀態：

/dev/kvm

存在。

---

6. 好的 這裡開始 安裝 Git / tmux

官方特別提醒：

kvm-qemu.sh 和 cape2.sh 建議在 tmux 中執行，避免 SSH 斷線導致安裝中斷。

所以優先更新：

sudo apt update
sudo apt install -y git tmux

然後：

tmux new -s cape

之後整個 CAPE 安裝都在這個 session 裡做。

---

7. 下載 CAPEv2

例如：

cd /opt
sudo git clone https://github.com/kevoreilly/CAPEv2.git
sudo chown -R $USER:$USER /opt/CAPEv2
cd /opt/CAPEv2

目前 CAPEv2 是 rolling development model，沒有傳統「每隔一段時間一個 release」的思維；官方要求你持續 pull 更新。

因此正式環境我反而建議：

先測試
   ↓
固定 Git commit
   ↓
驗證
   ↓
再升級

不要：

git pull

之後直接讓 production 跑。

---

8. 第一個大步驟：安裝 KVM/QEMU

進入：

cd /opt/CAPEv2/installer

先看說明：

./kvm-qemu.sh -h

官方安裝方式：

sudo chmod a+x kvm-qemu.sh
sudo ./kvm-qemu.sh all <username> 2>&1 | tee kvm-qemu.log

其中：

<username>

換成你的 Ubuntu 使用者。

例如：

sudo ./kvm-qemu.sh all john 2>&1 | tee kvm-qemu.log

---

9. kvm-qemu.sh 有一個非常重要的注意事項

官方要求你先看：

kvm-qemu.sh

並處理裡面的：

<WOOT>

sudo sed -i 's/<WOOT>/Custom/g' kvm-qemu.sh
sudo chmod a+x *.sh

這些是與硬體識別 / 虛擬化偵測相關的設定。

官方說明：

實驗室環境可以使用隨機 4 個字元；如果是要降低惡意程式對 VM 的辨識，則建議使用真實硬體資訊。

所以：

Lab
→ 隨機值即可

更高階 malware analysis
→ 需要另外研究 VM fingerprint / anti-VM

第一次部署先不要把這件事情複雜化。

---

10. 安裝 virt-manager

如果你想方便建立 Windows VM：

sudo ./kvm-qemu.sh virtmanager <username> | tee kvm-qemu-virt-manager.log

例如：

sudo ./kvm-qemu.sh virtmanager john | tee kvm-qemu-virt-manager.log

完成後：

sudo reboot

官方建議完成 KVM 安裝後 reboot。([GitHub][3])

---

11. KVM 安裝完成後先不要急著裝 CAPE

先測：

virsh list --all

以及：

virsh -c qemu:///system list --all

再啟動：

virt-manager

確認：

libvirt
QEMU
KVM
virt-manager

全部正常。

官方也特別提醒：

KVM/libvirt 沒正常之前，不要進下一階段。

因為後面 CAPE 的 VM machinery 都依賴它。([GitHub][3])

---

12. 建立 Windows Guest VM

官方目前建議：

Windows 10
或
Windows 11 23H2

並指出分析 VM 建議關閉 User Account Control（UAC）。([CAPE Sandbox][4])

我建議第一台：

Windows 10 x64

第二台再：

Windows 11 23H2

這樣可以比較不同 malware 對 OS 的行為。

---

13. Guest VM 硬體設定

沒有官方固定規格，所以第一台可以先：

vCPU       4
RAM        8 GB
Disk       60–100 GB
Disk type  QCOW2
NIC        1

KVM 特別注意：

QCOW2

官方要求 KVM Guest 使用可 Snapshot 的磁碟格式，例如 QCOW2 或 LVM；文件採 QCOW2 作為範例。([CAPE Sandbox][5])

不要第一台就使用：

RAW

然後才發現 snapshot 架構不方便。

---

14. Windows Guest 安裝 Python

這裡有一個很容易踩雷的地方。

目前官方 Guest requirements 說：

Windows Guest
Python 3.10 < version < 3.13
32-bit / x86

也就是：

Python 3.10 / 3.11 / 3.12
x86

官方文件明確警告，在 Windows Guest 使用 64-bit Python 可能導致 analyzer crash。([CAPE Sandbox][6])

而 README 的安裝建議仍寫著 agent.py 曾以 Python 3.7.2/3.8 x86 測試。這是目前 README 與較新的 Guest 文件存在時間差的地方；新部署應優先按照目前 Guest installation documentation 的版本範圍。([GitHub][1])

我會選：

Python 3.12 x86

---

15. Guest Python PATH

安裝 Python 時：

Add Python to PATH

然後：

python --version

再：

python -m pip install --upgrade pip
python -m pip install Pillow

Pillow 用於螢幕截圖等功能。([CAPE Sandbox][6])

---

16. Guest 不要裝成普通工作機

這台 Windows VM 的目的是：

Malware Detonation

不是：

Office 工作機

如果你需要測：

PDF Malware
Office Malware
Browser Malware
JavaScript
HTA
PowerShell
DOC / XLS

再依分析目的安裝對應軟體。

而且 CAPE 官方建議把額外軟體的：

Auto Update
Check for Updates

關掉，避免干擾分析結果。([CAPE Sandbox][6])

---

17. 安裝 CAPE Agent

從 Host：

/opt/CAPEv2/agent/agent.py

把它放進 Windows Guest。

官方要求每一台 Guest 都需要 Agent，而且 Agent 必須以 elevated privilege 啟動。([GitHub][7])

Windows 10+ 建議使用：

Task Scheduler

不要直接把它丟到一般 Startup folder。

官方建議：

Task Scheduler
   ↓
Create Basic Task
   ↓
When I log on
   ↓
Start a program
   ↓
agent.pyw
   ↓
Run with highest privileges

另外，可以把：

agent.py

改成：

agent.pyw

避免開 CMD 視窗干擾分析。([GitHub][7])

---

18. Agent 安裝後一定測試

假設 Guest：

192.168.122.100

Host 測：

curl http://192.168.122.100:8000

或者瀏覽器：

http://192.168.122.100:8000

Agent 正常後才繼續。

官方明確要求 Snapshot 前先驗證 Agent。([GitHub][7])

---

19. Windows Guest 網路設定

這是 CAPE 最重要的部分之一。

你不能只是：

Windows VM
   ↓
公司 LAN
   ↓
Internet

應該設計成：

                Management
                    │
Ubuntu Host ────────┤
                    │
             CAPE Network
                    │
                    ▼
               Windows VM

CAPEv2 有專門的：

routing.conf
rooter.py

來決定 Guest 的網路是否：

none
drop
internet
VPN
InetSim
Tor
SOCKS

官方預設 route = none，也就是不替 Guest 做 Internet routing。([GitHub][8])

---

20. 我特別建議第一階段：完全不要 Internet

初始部署先：

Windows VM
    │
    └── isolated network
             │
             X
          Internet

先驗證：

CAPE
→ VM 啟動
→ Agent
→ Sample
→ Process
→ Report

全部成功後，再研究：

Internet routing
InetSim
VPN
PCAP

不要第一次安裝就讓 malware 可以連 Internet。

---

21. 如果之後要開 Internet

CAPE 需要：

IP forwarding

官方文件：

sudo sysctl -w net.ipv4.ip_forward=1

也可以：

echo 1 | sudo tee -a /proc/sys/net/ipv4/ip_forward

但官方提醒這個設定重開機後不會自動持久化，除非另外配置。([CAPE Sandbox][9])

---

22. Guest 的 Firewall / Update

CAPE 官方文件建議為了避免干擾分析：

Windows Firewall
    ↓
Disable

Automatic Updates
    ↓
Disable

原因不是「安全性」，而是 Windows Firewall / Update 會改變 malware 的真實行為並產生額外 network noise。([CAPE Sandbox][10])

但這裡有一個非常重要的前提：

只有在高度隔離的 Malware Analysis 網路中才這麼做。

不能把這台 Guest 接到你的公司 LAN 後又把 Firewall 關掉。

---

23. 建立 Snapshot

這一步是 CAPE 能不能正常工作的核心。

流程：

Windows
 ↓
安裝乾淨
 ↓
Python
 ↓
Agent
 ↓
分析用軟體
 ↓
Network
 ↓
重開
 ↓
確認 Agent
 ↓
Snapshot

KVM 官方建議：

QCOW2

然後：

virsh snapshot-create-as --domain "<VM>" --name "<snapshot>"

官方要求 Snapshot 時 Guest 要：

Windows 已完整開機
Agent 正在跑

([CAPE Sandbox][5])

例如：

VM: win10-cape
Snapshot: clean

---

24. CAPE Host 安裝

回到 Ubuntu：

cd /opt/CAPEv2/installer

先：

./cape2.sh -h

這一步非常重要。

目前 cape2.sh 支援：

Base
All
Sandbox
Dependencies
Systemd
Nginx
LetsEncrypt
Suricata
PostgreSQL
Yara
Yara-x
Volatility3
Mongo
...

目前 All 的意思真的是「裝很多東西」，官方腳本自己也提醒不要在不知道內容的情況下直接使用。([GitHub][11])

---

25. 我建議第一次怎麼裝 CAPE

第一次 Lab，我建議：

sudo bash cape2.sh base | tee cape2.log

官方文件目前的安裝指令也有：

sudo ./cape2.sh base cape | tee cape.log

但目前 cape2.sh 本身的 usage/範例已經演進到：

sudo bash cape2.sh all | tee cape2.log

而且支援 CAPE_ROOT、USE_UV 等新參數。([GitHub][3])

因此：

請以你實際 checkout 的 cape2.sh -h 為準，不要盲目複製舊文章。

這是 CAPEv2 特別需要注意的地方。

---

26. Poetry / UV

目前官方推薦 Poetry，也已經加入 UV 支援。

預設：

/opt/CAPEv2
Poetry

或者新方式：

sudo CAPE_ROOT=/mnt/sandbox/CAPEv2 USE_UV=True bash cape2.sh all | tee cape2.log

目前 script 明確支援：

CAPE_ROOT
USE_UV=True

([GitHub][11])

我的建議：

第一次部署：

Poetry

先照官方預設。

第二套實驗環境，再研究：

UV

---

27. CAPE 服務

安裝後會有：

cape.service
cape-processor.service
cape-web.service
cape-rooter.service

([GitHub][3])

查：

systemctl status cape.service
systemctl status cape-processor.service
systemctl status cape-web.service
systemctl status cape-rooter.service

Log：

journalctl -u cape.service
journalctl -u cape-processor.service
journalctl -u cape-web.service
journalctl -u cape-rooter.service

官方也明確說只有某些工具，例如 rooter.py，需要 root；主要 CAPE 程式應該以 cape user 執行。全部用 root 跑反而容易造成 permission 問題。([GitHub][1])

---

28. CAPE 設定檔

至少要理解這幾個：

conf/cuckoo.conf
conf/auxiliary.conf
conf/kvm.conf
conf/memory.conf
conf/processing.conf
conf/reporting.conf
conf/routing.conf

官方要求至少要調整：

auxiliary.conf
cuckoo.conf
machinery.conf

其中：

cuckoo.conf
→ CAPE 基本設定

kvm.conf
→ 哪些 VM 可以跑

routing.conf
→ Guest 網路怎麼走

processing.conf
→ 結果怎麼分析

reporting.conf
→ 報告輸出

([CAPE Sandbox][12])

---

29. 不建議直接修改 default config

官方目前建議：

custom/conf/

例如：

custom/conf/cuckoo.conf
custom/conf/kvm.conf
custom/conf/routing.conf

只放你需要覆寫的設定。

這樣 CAPEv2 更新後比較不會把你的設定弄掉。([CAPE Sandbox][12])

這一點我很建議你遵守。

---

30. kvm.conf 要把你的 Windows VM 加進去

官方範例是：

[kvm]

machines = cuckoo1

interface = virbr0

dsn = qemu:///system

[cuckoo1]

label = cuckoo1
platform = windows
ip = 192.168.122.105
arch = x86

其中：

label

必須對得上：

virsh list --all

裡面的 VM 名稱。([GitHub][13])

---

31. Web UI

CAPE Web 預設可以在：

http://127.0.0.1:8000

啟動。

官方 production 部署則建議：

Gunicorn
+
NGINX

而且如果要暴露給其他人使用，應該啟用 Web authentication。([CAPE Sandbox][14])

因此第一個 Lab 不需要急著：

Internet
 ↓
NGINX
 ↓
CAPE

先：

管理端
 ↓
localhost:8000

即可。

---

32. 啟動 CAPE

如果使用 Poetry：

cd /opt/CAPEv2
sudo -u cape poetry run python3 cuckoo.py

官方也說明 CAPE 應該以 cape user 執行。([CAPE Sandbox][15])

測試模式：

sudo -u cape poetry run python3 cuckoo.py -t

Debug：

sudo -u cape poetry run python3 cuckoo.py -d

---

33. 第一個測試不要直接丟真 Malware

建議測試順序：

第 1：
安全測試檔

↓

第 2：
自己寫的簡單 EXE

↓

第 3：
EICAR

↓

第 4：
研究用途 Malware Sample

先確認：

Sample
 ↓
CAPE
 ↓
VM
 ↓
Agent
 ↓
ResultServer
 ↓
Processing
 ↓
Report

整條 pipeline 都正常。

---

34. 磁碟空間要特別注意

CAPE 會留下：

PCAP
memory dump
screenshots
dropped files
JSON
HTML
process dumps

而官方 cuckoo.conf 預設 free-space threshold 就是：

50 GB

([CAPE Sandbox][12])

所以：

100 GB SSD

不是我建議的正式 CAPE Storage。

第一台 Lab：

200 GB

比較舒服。

如果大量分析：

500 GB ~ 1 TB+

比較合理。

---

35. MongoDB / AVX 注意事項

這是目前 2026 版值得特別提醒你的地方。

目前 cape2.sh 預設會處理 MongoDB，而且腳本現在：

MongoDB 8.0

如果 CPU 有 AVX，走新版 MongoDB。

如果沒有 AVX，腳本會退回：

MongoDB 4.4

官方腳本也明確指出 MongoDB >= 5 需要 AVX。([GitHub][11])

所以你的 Host CPU 最好：

支援 AVX

這也是為什麼我不建議拿非常老舊 CPU 建 CAPEv2。

---

36. 更新 CAPEv2 不要直接 apt upgrade

這是官方很重要的一個警告。

CAPE 安裝腳本安裝的套件：

KVM
libvirt
Python dependencies
MongoDB
其他依賴

不要在不理解依賴關係的情況下：

apt upgrade

或：

apt install -f

官方明確警告，這可能把 KVM/libvirt/CAPE 的相依性弄壞。([GitHub][3])

尤其 kvm-qemu.sh 本身就有：

NEVER FORCE system upgrade

的警告。([GitHub][16])

---

37. CAPEv2 是 Rolling，不是「裝完就一年不動」

目前官方明確說：

CAPE is maintained and updated in a rolling fashion.

也就是：

沒有固定 release
沒有「裝 v2.6 就永遠固定」

所以正式環境應該：

Git commit
     ↓
Test Lab
     ↓
Validation
     ↓
Production

而不是：

git pull
systemctl restart cape*

然後直接祈禱。

([GitHub][3])

---

38. 最容易踩雷的地方

我幫你濃縮成這張表：

問題	風險
Ubuntu 版本不合	高
KVM 沒正常	高
nested virtualization	高
Guest Python 裝 x64	高
Agent 沒 administrator	高
Agent 沒在 8000 port	高
VM 沒 Snapshot	高
VM 名稱與 kvm.conf 不一致	高
resultserver IP 填錯	高
routing 設錯	非常高
Malware VM 接公司 LAN	非常高
Host/Guest 共用資料夾	高
不小心讓 Guest 出 Internet	非常高
所有 CAPE 程式都 sudo	高
apt upgrade 破壞 libvirt	高
磁碟太小	中/高
CPU 沒 AVX	中
直接 git pull production	中/高

---

39. 我最建議你採用的第一版架構

考慮你前面一直在研究：

Windows
Docker Desktop
Ubuntu
地端 AI
MCP
CAPEsolo

如果現在把 CAPEv2 也放進來，我會建議分成：

                  實體伺服器
                       │
               Ubuntu 24.04 LTS
                       │
        ┌──────────────┼─────────────┐
        │              │             │
        ▼              ▼             ▼
     CAPEv2          KVM          管理網卡
        │              │
        │        ┌─────┴─────┐
        │        │           │
        │      Win10       Win11
        │       VM           VM
        │        │            │
        │     Agent         Agent
        │
        └──────────────┐
                       │
                  Analysis Data
                       │
               JSON / PCAP / IOC
                       │
                       ▼
                 AI / LLM Host
                       │
                      MCP

而你的：

Docker Desktop / Ubuntu

繼續負責：

LLM
MCP
API
開發環境
Knowledge Base
ERP 開發

不要讓 Docker 成為 malware execution layer。

---

40. 最終安裝順序，我建議照這個 Checklist

[ ] 1. 準備 Ubuntu 24.04 LTS
[ ] 2. 確認 CPU VT-x / AMD-V
[ ] 3. 確認 /dev/kvm
[ ] 4. 安裝 git / tmux
[ ] 5. clone CAPEv2
[ ] 6. 閱讀 installer/kvm-qemu.sh
[ ] 7. 處理 <WOOT>
[ ] 8. 執行 kvm-qemu.sh
[ ] 9. reboot
[ ] 10. 驗證 KVM/libvirt
[ ] 11. 安裝 virt-manager
[ ] 12. 建立 Windows 10 / Win11 23H2 VM
[ ] 13. 使用 QCOW2
[ ] 14. 安裝 Python x86
[ ] 15. 安裝 Pillow
[ ] 16. 複製 agent.py
[ ] 17. Task Scheduler 啟動 Agent
[ ] 18. 測試 VM_IP:8000
[ ] 19. 建立隔離網路
[ ] 20. 配置 static IP
[ ] 21. 配置 CAPE routing
[ ] 22. 建立 clean snapshot
[ ] 23. 安裝 cape2.sh
[ ] 24. 驗證 Poetry / UV
[ ] 25. 驗證 cape.service
[ ] 26. 驗證 cape-processor.service
[ ] 27. 驗證 cape-web.service
[ ] 28. 驗證 cape-rooter.service
[ ] 29. 設定 custom/conf
[ ] 30. 設定 kvm.conf
[ ] 31. 測試 CAPE
[ ] 32. 測試 Web UI
[ ] 33. 測試第一個安全樣本
[ ] 34. 再進行 Malware Analysis

最後給你的部署建議

如果你是要「真的架一套」而不是只研究 GitHub，我會建議第一版直接採：

Ubuntu 24.04 LTS
        +
KVM/QEMU
        +
virt-manager
        +
Windows 10 x64 Guest
        +
Python 3.12 x86
        +
CAPE Agent
        +
QCOW2 Snapshot
        +
隔離分析網路
        +
CAPEv2

先把單 VM、無 Internet、可成功分析、可正常回復 Snapshot這條路跑通，再增加第二台 Windows 11、Internet Routing、InetSim、Suricata、MongoDB、Distributed CAPE、AI/MCP。

這樣排錯成本最低，也符合 CAPE 官方目前的部署方向。([CAPE Sandbox][17])

官方主要文件：

## 1. Host Installation

- [CAPEv2 GitHub Repository](https://github.com/kevoreilly/CAPEv2)
- [Host Installation](https://github.com/kevoreilly/CAPEv2/blob/master/docs/book/src/installation/host/installation.rst)
- [KVM/QEMU Installation Script](https://github.com/kevoreilly/CAPEv2/blob/master/installer/kvm-qemu.sh)
- [CAPE Installation Script](https://github.com/kevoreilly/CAPEv2/blob/master/installer/cape2.sh)
- [Host Configuration](https://capev2.readthedocs.io/en/latest/installation/host/configuration.html)

## 2. Guest VM

- [Guest Requirements](https://capev2.readthedocs.io/en/latest/installation/guest/requirements.html)
- [Create Virtual Machine](https://capev2.readthedocs.io/en/latest/installation/guest/creation.html)
- [Guest Agent](https://github.com/kevoreilly/CAPEv2/blob/master/docs/book/src/installation/guest/agent.rst)
- [Save / Snapshot Virtual Machine](https://capev2.readthedocs.io/en/latest/installation/guest/saving.html)

## 3. Network

- [Host Routing Configuration](https://github.com/kevoreilly/CAPEv2/blob/master/docs/book/src/installation/host/routing.rst)
- [Per-Analysis Network Routing](https://capev2.readthedocs.io/en/latest/installation/host/routing.html)
- [Guest Network Configuration](https://capev2.readthedocs.io/en/latest/installation/guest_physical/network.html)
- [KVM Configuration](https://github.com/kevoreilly/CAPEv2/blob/master/conf/default/kvm.conf.default)

## 4. Operation

- [Web Interface](https://capev2.readthedocs.io/en/latest/usage/web.html)
- [Starting CAPE](https://capev2.readthedocs.io/en/latest/usage/start.html)

## 5. Documentation

- [CAPE Sandbox Installation](https://capev2.readthedocs.io/en/latest/installation/)
- [CAPE Sandbox Documentation](https://capev2.readthedocs.io/en/latest/)